---
title: Laravel
description: How to use HeroUI with Laravel
---

# Laravel

Requirements:

- [Laravel 11](https://laravel.com/)
- [PHP v8.2](https://www.php.net/)
- [React 18](https://reactjs.org/) or later
- [Tailwind CSS v4](https://tailwindcss.com/docs/installation/framework-guides/laravel/vite)
- [Framer Motion 11.9](https://www.framer.com/motion/) or later

------

<CarbonAd/>

To use HeroUI in your Laravel project, you need to follow the following steps:

### Using HeroUI + Laravel template

If you are starting a new project, you can run one of the following commands to create a Laravel project pre-configured with HeroUI:

<PackageManagers
  commands={{
    npm: 'npx create-laravel@latest --template https://github.com/heroui-inc/laravel-template',
    yarn: 'yarn create laravel --template https://github.com/heroui-inc/laravel-template',
    pnpm: 'pnpm create laravel --template https://github.com/heroui-inc/laravel-template',
    bun: 'bunx create-laravel@latest --template https://github.com/heroui-inc/laravel-template',
  }}
/>

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

```codeBlock bash
heroui add button
```

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

```codeBlock bash
heroui add button input
```

Or you can add the main library `@heroui/react` by running the following command:

```codeBlock bash
heroui add --all
```

If you leave out the component name, the CLI will prompt you to select the components you want to add.

```codeBlock bash
? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◉  button
◯  card
◯  checkbox
◯  chip
◯  code
```

You still need to add the provider to your app manually (we are working on automating this step).

```jsx {3,7,9}
// app/providers.tsx

import {HeroUIProvider} from '@heroui/react'

export function Providers({children}: { children: React.ReactNode }) {
  return (
    <HeroUIProvider>
      {children}
    </HeroUIProvider>
  )
}
```

<Spacer y={4} />

```jsx {8,23,25}
// app.tsx or app.jsx
import '../css/app.css';
import './bootstrap';

import { createInertiaApp } from '@inertiajs/react';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
import { createRoot } from 'react-dom/client';
import { HeroUIProvider } from "@heroui/react";

const appName = import.meta.env.VITE_APP_NAME || 'Laravel';

createInertiaApp({
    title: (title) => `${title} - ${appName}`,
    resolve: (name) =>
        resolvePageComponent(
            `./Pages/${name}.tsx`,
            import.meta.glob('./Pages/**/*.tsx'),
        ),
    setup({ el, App, props }) {
        const root = createRoot(el);

        root.render(
            <HeroUIProvider>
                <App {...props} />
            </HeroUIProvider>
        );
    },
    progress: {
        color: '#4B5563',
    },
});
```

### Manual Installation

<Steps>

### Add dependencies

In your Laravel project, run one of the following command to install HeroUI:

<PackageManagers
  commands={{
    npm: 'npm i @heroui/react framer-motion',
    yarn: 'yarn add @heroui/react framer-motion',
    pnpm: 'pnpm add @heroui/react framer-motion',
    bun: "bun add @heroui/react framer-motion"
  }}
/>

### Hoisted Dependencies Setup

<Blockquote color="primary">
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
</Blockquote>

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

```bash
public-hoist-pattern[]=*@heroui/*
```

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official
[installation guide](https://tailwindcss.com/docs/installation/framework-guides/laravel/vite) to install Tailwind CSS. Then you need to add
the following code to your `tailwind.config.js` file:

<Blockquote color="primary">
**Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`
</Blockquote>

```js {2,8,13-14}
// tailwind.config.js
const { heroui } = require("@heroui/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [heroui()]
}
```

### Provider Setup

After installing HeroUI, you need to set up the `HeroUIProvider` at the `root` of your application.

Go to the src directory and inside `app.jsx` or `app.tsx`, wrap `HeroUIProvider` around App:

```jsx {8,23,25}
// app.tsx or app.jsx
import '../css/app.css';
import './bootstrap';

import { createInertiaApp } from '@inertiajs/react';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
import { createRoot } from 'react-dom/client';
import {HeroUIProvider} from "@heroui/react";

const appName = import.meta.env.VITE_APP_NAME || 'Laravel';

createInertiaApp({
    title: (title) => `${title} - ${appName}`,
    resolve: (name) =>
        resolvePageComponent(
            `./Pages/${name}.tsx`,
            import.meta.glob('./Pages/**/*.tsx'),
        ),
    setup({ el, App, props }) {
        const root = createRoot(el);

        root.render(
            <HeroUIProvider>
                <App {...props} />
            </HeroUIProvider>
        );
    },
    progress: {
        color: '#4B5563',
    },
});
```

</Steps>